DisposeResource is a debugging utility made to catch a common programming error: passing a resource handle to DisposeHandle().
The Resource Manager keeps track of in-memory resources by storing their handles in the resource map. If the block used by the resource is freed without letting the resource manager know [by calling ReleaseResource()], then the handle reference will not be removed from the resource map. This can lead to crashes and data loss.
Future allocations in the heap will likely re-use the master pointer for another relocatable block. If this happens, then the handle returned to the client will be the same value as the handle in the resource map. Magically [or sadly], the handle in the map will now suddenly refer to a random block in the heap. This data could be written out to the resource file, or trashed if LoadResource() is called on the “resource” handle.
DisposeResource will break into the debugger if DisposeHandle() is ever passed a handle referring to a block with the resource attribute set. This usually will be a resource handle, but be aware that the resource attribute could be set on a non-resource handle. This isn’t likely [unless someone was a complete bonehead], but it’s possible.
Version 2.0
DisposeResource now checks for ROM resources. ROM resources cannot be detached, and therefore always have their resource bit set. Calling DisposeHandle on a ROM resource does nothing [did you think a chuck of you ROM would be removed?], and this version ignores this circumstance. The most satisfied customer of this new DisposeResource is Sound Manager 3.1 which correctly calls DetachResource() and DisposeHandle() on a resource which happens to be in ROM. So you can stop sending in those bug reports.
Greg Marriott
Just Some Guy
[at General Magic, channeling through Jim Reekes at Apple Computer, Inc.]
